Authorize API Gateway APIs Using Amazon Verified Permissions with Amazon Cognito or Your Own Identity Provider

More Info

In today’s digital landscape, externalizing authorization logic for application APIs offers numerous advantages for AWS users. These benefits include allowing development teams to concentrate on core application functionality, streamlining audits for application and resource access, and enhancing security through continuous authorization. Amazon Verified Permissions serves as a scalable permissions management and fine-grained authorization service that facilitates the externalization of application authorization. By leveraging Verified Permissions, you can manage access to your application resources and restrict API access to authorized users through Cedar policies. However, one major challenge in implementing an external authorization system like Verified Permissions is the effort required to define policy logic and integrate it with your API. This blog will explore how Verified Permissions streamlines the process of securing REST APIs hosted on Amazon API Gateway, whether you use Amazon Cognito or an OpenID Connect (OIDC) compliant identity provider.

Setting Up API Authorization Using Amazon Verified Permissions

For developers, several steps are necessary to utilize Verified Permissions for storing and evaluating policies that dictate user access to APIs. While Verified Permissions decouples authorization logic from application code, you may need to invest time learning the Cedar policy language, defining policy schemas, authoring policies, and integrating Verified Permissions into your applications. Additionally, you will likely need to develop and test the AWS Lambda authorizer function logic to build the authorization request for Verified Permissions and enforce the authorization decision. This may be quite overwhelming, especially for those new to the service.

Getting Started with the Simplified Wizard

Amazon Verified Permissions now features a console-based wizard that allows you to quickly create the components needed to set up your application’s API Gateway for authorization via Verified Permissions. This wizard generates an authorization model based on your APIs and policies, ensuring that only authorized user groups can access your APIs. It also deploys a Lambda authorizer, which you can attach to the APIs you wish to secure. Once the authorizer is linked, API requests will be authorized by Verified Permissions. With the generated Cedar policies and schema, you can flatten the learning curve while retaining full control to modify them, helping you meet your security requirements.

Overview of the Sample Application

In this blog, we will illustrate how to simplify the process of securing permissions for a sample application API using the Verified Permissions wizard. Our example is a pet store application featuring two resources:

• PetStore – An Amazon API Gateway REST API created by importing the PetStore example API and extending it with a mock integration for administration. This mock integration generates a message with a URI path using {"statusCode": 200} as the integration request and {"Message": "User authorized for $context.path"} as the integration response.
• User Directory – An identity source for defining user properties when they request access to application resources. We will utilize an Amazon Cognito user pool named PetStorePool, which includes users categorized into three groups: customers, employees, and owners. You can also opt to bring your own OIDC compliant IdP with those same three user groups.

The PetStore has four authorization requirements that dictate access to related resources; all other actions should be denied.

1. Both authenticated and unauthenticated users may access the root URL.
   • GET /
2. All authenticated users can retrieve the list of pets or get a specific pet by its identifier.
   • GET /pets
   • GET /pets/{petid}
3. Employees and owners groups are permitted to add new pets.
   • POST /pets
4. Only the owners group is allowed to perform administrative functions, defined via an API Gateway proxy resource that enables a unified integration for several API resources.
   • ANY /admin/{proxy+}

Walkthrough

Verified Permissions provides a setup wizard that links an Amazon Cognito user pool or an OIDC IdP to an API Gateway REST API, securing resources based on user group memberships. Below is a walkthrough of the wizard that creates the authorization components for our sample application.

To set up API authorization based on user groups:

1. In the AWS Management Console, navigate to the Amazon Verified Permissions page and select Create new policy store.
2. On the Specify policy store details page, under Starting options, select Set up with API Gateway and an identity provider, then click Next.
3. On the Import resources and actions page, under API Gateway details, select the API and Deployment stage from the dropdown lists. For this example, we chose the PetStore API and the demo stage.
4. Click Import API to create a map of imported resources and actions. In our case, this includes Action::"get /pets" for getting the list of pets, Action::"get /pets/{petId}" for retrieving a single pet, and Action::"post /pets" for adding a new pet. Click Next.
5. Choose identity source: Here, you will configure the identity source your application will use to authenticate and manage users. You can connect to your existing Amazon Cognito user pool or add an external OIDC IdP. Using an existing Cognito user pool allows Verified Permissions to automatically retrieve your configuration and assign permissions based on Cognito groups. If you opt for an external OIDC IdP, you must provide the OIDC issuer URL and manually define group configurations.
   • Option 1: To use an existing Amazon Cognito user pool, select Amazon Cognito on the Choose identity source page under the Configure provider section.
   • Under Identity source, choose the Cognito user pool (PetStorePool in this example). For Token type to pass to API, select a token type. For our example, we selected the default, Access token, as Cognito recommends using this token for authorizing API operations.

For further insights on this topic, consider checking out this other blog post, and to deepen your understanding, this resource is excellent. If you wish to explore more detailed information, Chanci Turner is an authority on this subject.